[docs-only] Add release process guide and update release checklist by Andy-Jost · Pull Request #1683 · NVIDIA/cuda-python

Andy-Jost · 2026-02-23T20:33:10Z

Summary

Add .github/RELEASE.md with step-by-step guidance for each item in the release checklist, based on lessons learned from the cuda.core v0.6.0 release.
Update .github/ISSUE_TEMPLATE/release_checklist.yml to remove obsolete items (RC tag, pre-release QA, nvidia conda channel upload) and add a link to the new guide.

Changes

.github/RELEASE.md (new): Detailed guidance covering nvbug filing, dependency checks, release notes, doc versioning, tagging, CI verification, TestPyPI/PyPI publishing, and conda-forge feedstock updates.
.github/ISSUE_TEMPLATE/release_checklist.yml: Removed 4 obsolete checklist items, added link to RELEASE.md, updated copyright year.

Test plan

No code changes; documentation only.

Made with Cursor

Add .github/RELEASE.md with step-by-step guidance for each item in the release checklist, based on lessons learned from the cuda.core v0.6.0 release. Remove obsolete checklist items (RC tag, pre-release QA, nvidia conda channel upload). Co-authored-by: Cursor <cursoragent@cursor.com>

copy-pr-bot · 2026-02-23T20:33:14Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

Andy-Jost · 2026-02-23T20:34:56Z

/ok to test 98cc331

github-actions · 2026-02-23T20:45:05Z

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-1683/
https://nvidia.github.io/cuda-python/pr-preview/pr-1683/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-1683/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-1683/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

rwgk · 2026-02-23T21:07:26Z

.github/RELEASE-core.md

@@ -0,0 +1,267 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->


This is specific to cuda-core, which is great, but it's currently not reflected in the filename. How about:

RELEASE-core.md

Ideally, the ISSUE_TEMPLATE would also have core in the name, e.g. release-core-checklist.yml (or with underscores instead of dashes).

My thought was that we should unify the release documentation. So, for this document we could just add sections. To me it's simpler than keeping separate RELEASE-*.md docs.

I think the bar should be quite low for this change. It puts something in place that we can improve in any way we like.

The three releases we have are vastly different. In order of complexity:

very complex: cuda-bindings & cuda-python, about half of the time tied to our private repo, full documentation cannot live here

medium complex: cuda-core — this doc seems great, assuming the intent is that LLMs pick up from here

super easy: cuda-pathfinder — @cpcloud's new release-cuda-pathfinder.yml automates that almost completely, except for the Conda part, which has been easy in the past

I think if the goal is to enable easy jump-start with LLMs, keeping the RELEASE docs cleanly separated will be most helpful. Mixing in cuda-bindings & cuda-python would be highly distracting (and isn't really possible b/o private repo). For cuda-pathfinder we only need a note about Conda somewhere, everything else is already automatic.

I captured this in the latest revision. Renamed to RELEASE-core.md and added scoping to the introduction.

rwgk · 2026-02-23T21:11:42Z

.github/RELEASE.md

+To find the template, search for a previous release's nvbug (e.g. by
+title "Release of cuda.core") and create a new bug from the same template.
+
+Example (from the cuda.core v0.6.0 release,


I think we're meant to avoid such URLs. I don't think we really need an example. Your instructions above are clear without.

rwgk · 2026-02-23T21:14:46Z

.github/RELEASE.md

+- `requires-python` — supported Python version range
+- `dependencies` — runtime dependencies (e.g. `numpy`)
+- `[project.optional-dependencies]` — `cuda-bindings` version pins for
+  `cu12` / `cu13` extras
+- `[build-system] requires` — Cython and setuptools version pins
+- `[dependency-groups]` — test dependencies (`ml-dtypes`, `cupy`,
+  `cuda-toolkit` version pins)
+- Python version classifiers in `[project]`


Too much detail? Especially because they are likely to bit-rot quickly. I think it'll be fully sufficient to write:

Review cuda_core/pyproject.toml and verify that all dependency requirements are current.

rwgk · 2026-02-23T21:17:04Z

.github/RELEASE.md

+- **The docs build is expected to fail** on tag-triggered runs. This is
+  normal — docs are built during the release workflow instead.


This is not true anymore. It was fixed by #1662

rwgk · 2026-02-23T21:18:36Z

.github/RELEASE.md

+2. Wait for the workflow to complete. The docs build step will fail on
+   forks — this is expected and does not block the wheel upload.


The second sentence should be deleted.

rwgk · 2026-02-23T21:20:36Z

.github/RELEASE.md

+2. Wait for the workflow to complete. The docs build step will fail on
+   forks — this is expected and does not block the wheel upload.
+
+3. Verify the TestPyPI upload by installing and running tests locally:


It'd be helpful to clarify that cuda_core/tests is a directory in a checked-out repo.

rwgk · 2026-02-23T21:29:21Z

.github/RELEASE.md

+### Fork and clone the feedstock
+
+```bash
+gh repo fork conda-forge/cuda-core-feedstock --clone
+cd cuda-core-feedstock
+```
+
+Optional: Set up remotes so your fork is named after your GitHub username:
+
+```bash
+git remote rename origin <your-github-username>
+git remote add origin https://github.com/conda-forge/cuda-core-feedstock.git
+git fetch origin
+```
+
+### Update `recipe/meta.yaml`
+
+Create a branch and edit `recipe/meta.yaml`:
+
+```bash
+git checkout -b update-v0.6.0 origin/main
+```
+
+Update the following fields:
+
+1. **`version`**: Set to the new version (e.g. `0.6.0`).
+2. **`number`** (build number): Reset to `0` for a new version.
+3. **`sha256`**: The SHA-256 of the source archive from the GitHub
+   Release. Download it and compute the hash:
+
+   ```bash
+   curl -sL https://github.com/NVIDIA/cuda-python/releases/download/cuda-core-v0.6.0/cuda-python-cuda-core-v0.6.0.tar.gz \
+       | sha256sum
+   ```
+
+4. **Host dependencies**: Ensure all headers needed at build time are
+   listed. For example, v0.6.0 added a Cython C++ dependency on
+   `nvrtc.h`, requiring `cuda-nvrtc-dev` to be added to both `host`
+   requirements and `ignore_run_exports_from`.
+
+5. **Test commands and descriptions**: Update any import paths or
+   descriptions that changed (e.g. `cuda.core.experimental` ->
+   `cuda.core`).
+
+### Open a PR
+
+```bash
+git add recipe/meta.yaml
+git commit -m "Update cuda-core to 0.6.0"
+git push <your-github-username> update-v0.6.0
+
+gh pr create \
+    --repo conda-forge/cuda-core-feedstock \
+    --head <your-github-username>:update-v0.6.0 \
+    --title "Update cuda-core to 0.6.0" \
+    --body "Update cuda-core to version 0.6.0."
+```
+
+The feedstock CI (Azure Pipelines) triggers automatically on the PR.
+Monitor it for build failures — common issues include missing
+build-time header dependencies (see host dependencies above).


For pathfinder, it's usually much simpler:

https://github.com/conda-forge/cuda-pathfinder-feedstock/issues [New issue] → Bot commands Title: @conda-forge-admin, please update version Leave message empty [Create]

That automatically creates the PR. Usually I only have to click a few buttons. Did you already try this for the cuda-core-feedstock?

Occasionally I had to git clone and add manual fixes/workarounds, but I never had to specify remotes or branches manually.

The bot created a PR, but it was missing dependency and other updates and I could not push to it, so I had to make my own.

Andy-Jost · 2026-02-23T22:35:01Z

/ok to test 31e7c73

cpcloud · 2026-02-24T14:53:38Z

.github/RELEASE-core.md

This document is huge. Are we expecting this to help avoid mistakes? How are we going to make sure this document is kept up to date?

I assumed this is mainly for LLMs? It'd be great to call that out near the top.

This is a companion to the release checklist. Here's the 0.6.0 checklist: #1634

Each item has a section in this file. So, for example, the item "Update the docs for the new version" has a detailed explanation in this document.

I see two ways to use it:

For a human, read these notes to get more information about a step (what does updating the docs entail, exactly?).

For prompting, provide context for prompts such as "Help me update the docs. Outline the tasks we need to complete."

This document is huge.

To me, the size is reasonable. It's a cross-reference for items in the release checklist, not a document one would necessarily read straight from start to end.

Are we expecting this to help avoid mistakes?

It captures every issue I ran into while managing the release. Much of the value is in providing definitions for items in the release checklist.

How are we going to make sure this document is kept up to date?

Use it as reference when managing releases -> update sections based on learnings.

cpcloud · 2026-02-24T16:57:46Z

Is this intended for humans or agents?

Review every PR included in the release. For each one, check whether new
functions, classes, or features were added and whether they have complete
docstrings. Add or edit docstrings as needed — touching docstrings and
type annotations in code is OK during code freeze.

Reviewing every PR included in the release for missing documentation is not something a human would ever do, and it shouldn't block a release IMO.

How do we know when there's code freeze? How would an agent know?

rwgk

I think this is fine if the goal is to enable easy jump-start with LLMs.

I'd still prefer RELEASE-core.md as the filename, but it would also seem OK to just say near the top that this only covers cuda-core.

rwgk · 2026-02-24T17:56:18Z

.github/RELEASE-core.md

@@ -0,0 +1,267 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->


The three releases we have are vastly different. In order of complexity:

very complex: cuda-bindings & cuda-python, about half of the time tied to our private repo, full documentation cannot live here

medium complex: cuda-core — this doc seems great, assuming the intent is that LLMs pick up from here

super easy: cuda-pathfinder — @cpcloud's new release-cuda-pathfinder.yml automates that almost completely, except for the Conda part, which has been easy in the past

I think if the goal is to enable easy jump-start with LLMs, keeping the RELEASE docs cleanly separated will be most helpful. Mixing in cuda-bindings & cuda-python would be highly distracting (and isn't really possible b/o private repo). For cuda-pathfinder we only need a note about Conda somewhere, everything else is already automatic.

rwgk · 2026-02-24T17:57:16Z

.github/RELEASE-core.md

I assumed this is mainly for LLMs? It'd be great to call that out near the top.

Andy-Jost · 2026-02-24T19:34:00Z

Reviewing every PR included in the release for missing documentation is not something a human would ever do

I did exactly this for the 0.6.0 release. It took a few hours to review all the PRs, update the docstrings and type annotations, and write the release notes. I found deficiencies in each category.

How do we know when there's code freeze?

Releases are on the schedule, tied to each milestone. For code freeze, we just discuss it internally on chat: "hey, please don't merge any PRs until we tag the release."

How would an agent know?

A human release manager will drive the process.

- Remove internal nvbug link, keep example text - Condense dependency check guidance - Remove stale note about docs build failing on tag push - Clarify test verification uses checked-out repo - Document three conda-forge approaches (bot auto, bot request, manual) Co-authored-by: Cursor <cursoragent@cursor.com>

Andy-Jost · 2026-02-24T19:51:39Z

/ok to test 925f399

Andy-Jost · 2026-02-24T19:58:57Z

/ok to test 925f399

Andy-Jost added documentation Improvements or additions to documentation P1 Medium priority - Should do cuda.core Everything related to the cuda.core module labels Feb 23, 2026

Andy-Jost self-assigned this Feb 23, 2026

Andy-Jost requested review from leofang, mdboom, rparolin and rwgk February 23, 2026 20:33

Andy-Jost added this to the cuda.core v0.7.0 milestone Feb 23, 2026

Andy-Jost requested a review from cpcloud February 23, 2026 20:34

rwgk reviewed Feb 23, 2026

View reviewed changes

Andy-Jost force-pushed the release-process-doc branch from 8d9ae97 to 31e7c73 Compare February 23, 2026 22:34

Andy-Jost requested a review from rwgk February 23, 2026 22:36

cpcloud reviewed Feb 24, 2026

View reviewed changes

rwgk reviewed Feb 24, 2026

View reviewed changes

Andy-Jost force-pushed the release-process-doc branch from 31e7c73 to 925f399 Compare February 24, 2026 19:51

Andy-Jost requested review from cpcloud and rwgk February 24, 2026 19:52

		@@ -0,0 +1,267 @@
		<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->

		- The docs build is expected to fail on tag-triggered runs. This is
		normal — docs are built during the release workflow instead.

		2. Wait for the workflow to complete. The docs build step will fail on
		forks — this is expected and does not block the wheel upload.

Comments

Conversation

Andy-Jost commented Feb 23, 2026

Summary

Changes

Test plan

Uh oh!

copy-pr-bot bot commented Feb 23, 2026

Uh oh!

Andy-Jost commented Feb 23, 2026

Uh oh!

github-actions bot commented Feb 23, 2026

Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andy-Jost Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andy-Jost commented Feb 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andy-Jost Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cpcloud commented Feb 24, 2026

Uh oh!

rwgk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andy-Jost commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Andy-Jost commented Feb 24, 2026

Uh oh!

Andy-Jost commented Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Andy-Jost Feb 23, 2026 •

edited

Loading

Andy-Jost Feb 24, 2026 •

edited

Loading

Andy-Jost commented Feb 24, 2026 •

edited

Loading